dxp-ux
GET BillingAccountByID (TMF666)
This operation retrieves a billing account entity used by:
- PR - billingAccountID (or) MSISDN (or) client accountId (or) BAN-CAN.
- PA - BillingAccountId.
URL
http://[localhost]:[port]/dxp-ux/v1/{businessId}/billingAccount/{id}URL PARAMS
| name | type | description | required |
|---|---|---|---|
| businessId | string | 2 letter ISO 3166 country code (TT, BB, JM, PA, PR etc.) identifying the business unit. Expected one is "PR"-Puerto Rico | Y |
| id | string | To retrieve 'account' information provide Billing Account Number or msisdn To retrieve 'balance' information provide account number. Example: msisdn: 17874047209,billingAccountNumber: 33541396-33542750 | Y |
Header
Note:
- For PR, To retrieve 'balance' information need to pass 'targetSystem'.
- To retrieve 'account' information need to pass 'lob'.
| name | value | description | required |
|---|---|---|---|
| client_id | string | The client_id identifying the channel. | Y |
| client_secret | string | Password associated with the client_id. | Y |
| X-Correlation-ID | string | An identifier for the current call chain that can be used to tie together log entries on multiple layers (e.g. client, server, mainframe). This identifier must be designed to be unique across all applications. Note - Mule default behavior creates a sample x-correlation-id field if value is not passed from client, API will use this value in case value is not passed in API request | Y |
| channelId | string | Expected value APP | Y (PR), N(PA) |
| lob | String | Enum: PREPAID, POSTPAID,FIXED Expected value for PR: PREPAID, POSTPAID Expected value for PA: FIXED, POSTPAID | Y (PR), N(PA) |
| targetSystem | String | Expected value "aria". | Y (PR), N(PA) |
Query Parameters
Note: For PR, To retrieve 'account' information need to pass 'extendedCharacteristics.name', 'extendedCharacteristics.value', 'type'.
| Name | value | description | required (mandatory-Y, optional-N, Not applicable- N/A) |
|---|---|---|---|
| extendedCharacteristics.name | string | Expected value is sourceSystem | Y(PR), N/A(PA) |
| extendedCharacteristics.value | string | Expected value is Digital | Y(PR), N/A(PA) |
| type | string | Need to pass 'billingAccountNumber' or 'msisdn' | Y(PR), N/A(PA) |
Data Model - Response:
| name | type | description | required (mandatory-Y, optional-N, Not applicable- N/A) |
|---|---|---|---|
| id | string | Billing Account Number (For PR: Salesforce Record Id) | Y (PA) N(PR) |
| href | string | URL reference of the billing account in Salesforce | N/A(PA) N(PR) |
| billable | boolean | The billability of the account | Y(PA) N/A(PR) |
| accountType | string | A categorization of an account, Possible Value - RES | Y (PA) N(PR) |
| ratingType | string | payment type of the billing account and the options are:Prepaid Postpaid | N/A(PA) N(PR) |
| description | string | customerType description. For PR: name of the account owner | Y (PA) N(PR) |
| name | string | name of the billing account | Y (PA) N(PR) |
| state | string | Contains the lifecycle state. | Y (PA) N(PR) |
| paymentStatus | string | The account's delinquency status or payment status. | Y (PA) N(PR) |
| lastModified | string | Date of last modification of the account | N/A (PA) N(PR) |
| autopayEnabled | string | indicator of the Auto Pay enabled | N/A (PA) N(PR) |
| extendedCharacteristics | array | A list of characteristics that characterize this billingAccount | N/A (PA) N(PR) |
| extendedCharacteristics.name | string | Name of the characteristic Example: methodType,token,externalPaymentMethodIdentifier | N/A (PA) N(PR) |
| extendedCharacteristics.value | string | The value of the characteristic Example: BrainTreeToken,639338417,2 | N/A (PA) N(PR) |
| accountBalance | array | Balances linked to the account | Y (PA) N(PR) |
| accountBalance.balanceType | string | Type of the balance | Y (PA) N(PR) |
| accountBalance.amount | object | Balance amount | Y (PA) N(PR) |
| accountBalance.amount.unit | string | USD, PAB | Y (PA) N(PR) |
| accountBalance.amount.value | number | A positive floating point number | Y (PA) N(PR) |
| accountBalance.validFor | object | A period, either as a deadline (endDateTime only) a startDateTime only, or both | N (PA) N(PR) |
| accountBalance.validFor.endDateTime | datetime or string | End of the time period, using ISO 8601 format Note for PA:This field type is string | N (PA) N(PR) |
| accountBalance.validFor.startDateTime | datetime or string | Start of the period, using ISO 8601 format. If you define a start, you must also define an end Note for PA:This field type is string | N (PA) N(PR) |
| accountRelationship | array | Significant connection between accounts. For instance an aggregating account for a list of shop branches each having its billing account | N (PA, PR) |
| accountRelationship.relationshipType | string | Type of relationship. | N/A (PA), N(PR) |
| accountRelationship.account | object | An account may be a party account or a financial account. | N/A (PA), N(PR) |
| accountRelationship.account.id | string | Unique identifier Id of the EntityDescriptionRef. | N/A (PA), N(PR) |
| accountRelationship.account.description | string | Detailed description of the EntityDescriptionRef | N/A (PA), N(PR) |
| accountRelationship.account.name | string | Name of the account. | N/A (PA), N(PR) |
| accountRelationship.account.@type | string | When sub-classing, this defines the sub-class entity name | N/A (PA), N(PR) |
| accountRelationship.validFor.endDateTime | datetime | End of the time period, using ISO 8601 format | N/A (PA), N(PR) |
| accountRelationship.validFor.startDateTime | datetime | Start of the period, using ISO 8601 format. If you define a start, you must also define an end | N/A (PA), N(PR) |
| billStructure | object | The structure of the bill for party accounts (billing or settlement). | Y (PA, PR) |
| billStructure.cycleSpecification | object | An attachment by value or by reference. | Y (PA, PR) |
| billStructure.cycleSpecification.id | string | Unique identifier of the billing cycle specification | Y (PA, PR) |
| billStructure.cycleSpecification.billingDay | Integer | Customer's billing cycle starts or ends. | Y (PA, PR) |
| billStructure.cycleSpecification.paymentDueDate | dateTime or string | An offset of a payment due date. The offset is expressed as number of days with regard to the start of the BillingPeriod Note for PA:This field type is string | Y (PA, PR) |
| billStructure.cycleSpecification.name | string | Expected value "monthly Billing" "bi-monthly billing" | N/A (PA), N(PR) |
| billStructure.cycleSpecification.dateShift | string | An offset of a billing/settlement date. The offset is expressed as number of days with regard to the start of the billing/settlement period. | Y (PA, PR) |
| billStructure.cycleSpecification.frequency | string | Possible values are "monthly" or "bi-monthly billing". | N/A (PA), N(PR) |
| billStructure.presentationMedia.name | string | Possible values are "Mail","Email, "eBill enabled" | Y (PA), N(PR) |
| billStructure.presentationMedia.id | string | Unique identifier of the bill presentation media | Y (PA), N(PR) |
| contact | array | Contact point for a given account and accessed via some contact medium. | Y (PA) N(PR) |
| contact.name | string | name of the contact | Y (PA) N(PR) |
| contact.partyRoleType | string | Identifies what kind of party role type is linked to the contact Ex: Owner | Y (PA) N(PR) |
| contact.contactMedium | array | Indicates the contact medium that could be used to contact the party. Possible values are | Y (PA) N(PR) |
| contact.contactMedium.mediumType | string | Type of the contact medium, possible values are: "BillingAddress", "Phone" or "PostalAddress". | Y (PA) N(PR) |
| contact.contactMedium.preferred | boolean | If true, it indicates that it is the preferred contact medium. Ex: true,false | Y (PA) N(PR) |
| contact.contactMedium.characteristic | object | Any additional characteristic(s) of this contact medium. | Y (PA) N(PR) |
| contact.contactMedium.characteristic.contactType | string | For PR: if mediumType = "Phone" then possible values are "Home","Business" | Y (PA) N(PR) |
| contact.contactMedium.characteristic.city | string | The city | Y (PA) N(PR) |
| contact.contactMedium.characteristic.country | string | The country | Y (PA) N(PR) |
| contact.contactMedium.characteristic.postCode | string | Postcode | Y (PA) N(PR) |
| contact.contactMedium.characteristic.stateOrProvince | string | State or province | Y (PA) N(PR) |
| contact.contactMedium.characteristic.street1 | string | Describes the street | Y (PA) N(PR) |
| contact.contactMedium.characteristic.street2 | string | Describes the street | Y (PA) N/A(PR) |
| contact.contactMedium.characteristic.phoneNumber | string | phone number of the customer | Y (PA) N(PR) |
| contact.contactMedium.characteristic.emailAddress | string | email address of the customer | Y (PA) N(PR) |
| contact.relatedParty | object | Related Entity reference | N/A (PA) N(PR) |
| contact.relatedParty.id | string | last 4 digits of SSN number | N/A (PA) N(PR) |
| contact.relatedParty.name | string | name of the customer account | N/A (PA) N(PR) |
| contact.relatedParty.@type | string | hard-coded as "relatedParty" | N/A (PA) N(PR) |
| creditLimit | object | The maximum amount of money that may be charged to an account | Y (PA) N(PR) |
| creditLimit.unit | string | USD, PAB | Y (PA) N(PR) |
| creditLimit.value | integer | value | Y (PA) N(PR) |
| defaultPaymentMethod | object | The maximum amount of money that may be charged on an account | Y (PA) N(PR) |
| defaultPaymentMethod.id | string | Unique identifier ID of the default payment method. Possible values are "C" "E" "" | Y (PA) N(PR) |
| defaultPaymentMethod.name | string | Payment Method Name. Possible values for PR: "Credit Card" "EFT" "Non Default Payment Method" Possible values for PA: "Electronic", "Cash" | Y (PA) N(PR) |
| financialAccount | object | AccountReceivable reference. An account of money owed by a party to another entity in exchange for goods or services that have been delivered or used. An account receivable aggregates the amounts of one or more party accounts (billing or settlement) owned by a given party. | Y (PA) N(PR) |
| financialAccount.id | string | AccountNumber of the financial account. For PR: Hard coded as "2063" | Y (PA) N(PR) |
| financialAccount.accountBalance | object | Balances linked to the account | N/A (PA) N(PR) |
| financialAccount.accountBalance.balanceType | string | Type of the balance ; DelinquentBalance, LastPaymentAmount, ReceivableBalance | N/A (PA) N(PR) |
| financialAccount.accountBalance.amount | string | Balance amount | N/A (PA) N(PR) |
| financialAccount.accountBalance.amount.unit | string | USD, PAB | N/A (PA) N(PR) |
| financialAccount.accountBalance.validFor | object | A period, either as a deadline (endDateTime only) a startDateTime only, or both | N/A (PA) N(PR) |
| financialAccount.accountBalance.validFor.endDateTime | datetime | End of the time period, using ISO 8601 format | N/A (PA) N(PR) |
| financialAccount.accountBalance.validFor.startDateTime | datetime | start of the time period | N/A (PA) N(PR) |
| financialAccount.@referredType | string | possible value is "financialAccount" | Y (PA) N(PR) |
| paymentPlan | array | A list of payment plans | Y (PA) N(PR) |
| paymentPlan.paymentFrequency | string | Frequency of the payments, such as monthly and bimonthly | N/A (PA) N(PR) |
| paymentPlan.planType | string | status of autopsy. possible values are "Auto Pay Enable" , "Auto Pay Disable | Y (PA) N(PR) |
| paymentPlan.priority | number | Priority of the payment plan. possible values are 0, 1 | Y (PA) N(PR) |
| paymentPlan.@Type | string | this defines the sub-class entity name | Y (PA) N/A(PR) |
| paymentPlan.status | string | Status of the payment plan | Y (PA) N/A(PR) |
| paymentPlan.paymentMethod | object | A payment method reference | N/A (PA) N(PR) |
| paymentPlan.paymentMethod.id | string | internal reference id of the payment method in Salesforce | N/A (PA) N(PR) |
| paymentPlan.extendedCharacteristics | array | A list of characteristics that characterize the payment method details | N/A (PA) N(PR) |
| paymentPlan.extendedCharacteristics.name | string | Name of the characteristic | N/A (PA) N(PR) |
| paymentPlan.extendedCharacteristics.value | string | Value of the characteristic | N/A (PA) N(PR) |
| characteristic | array | Describes a given characteristic of an object or entity through a name/value pair. | N/A (PA) N(PR) |
| characteristics.name | string | Name of the characteristic."LocationId" "DunningGroup" "DelinquencyDays" "autoPayDate "DebitDay" "CreditScore" | N/A (PA) N(PR) |
| characteristics.value | string | Value of the characteristic | N/A (PA) N(PR) |
| relatedParty | array | Related Entity reference | Y (PA), N(PR) |
| relatedParty.id | string | Customer Id | Y (PA), N(PR) |
| relatedParty.name | string | Customer name | Y (PA), N(PR) |
| relatedParty.role | string | role of the party. "customer" | Y (PA), N(PR) |
| relatedParty.@baseType | string | When sub-classing, this defines the super-class | Y (PA), N/A(PR) |
| relatedParty.@type | string | When sub-classing, this defines the sub-class entity name | Y (PA), N/A(PR) |
| relatedParty.@referredType | string | Reference type. "customer" | Y (PA), N(PR) |
| relatedParty.characteristics.name | string | Name of the characteristic. | Y (PA), N(PR) |
| relatedParty.characteristics.value | any | Value of the characteristic | Y (PA), N(PR) |
| relatedParty.characteristics.valueType | string | ValueType of the characteristic | Y (PA), N(PR) |
| @type | string | Type of the reference. "BillingAccount" | Y (PA), N(PR) |
| sourceBSS | string | BSS sytem from which the details are retrieved | Y (PA), N/A(PR) |
RelatedParty Characteristic subResource - dataModel
| characteristic name | type | description | required (mandatory-Y, optional-N, Not applicable- N/A) | examples |
|---|---|---|---|---|
| DocumentType | array | It provides the identity type | N (PA) | PA: { "name": "DocumentType", "value": "C" } |
| DocumentNumber | string | Indicated the identity number | N (PA) | PA: { "name": "DocumentNumber", "value": "4-248-586" } |
| string | Customer's email address | N (PA) | PA: { "name": "Email", "value": "argelis.samudio@cwpanama.com" } | |
| Gender | string | Indicates the gender of customer | N (PA) | PA: { "name": "Gender", "value": "F" } |
| Title | string | Provides the Salutation | N (PA) | PA: { "name": "Title", "value": "Sra", "valueType": "string" } |
| FirstName | string | Indicates the first name of customer | N (PA) | PA: { "name": "FirstName", "value": "Argelis", "valueType": "string" } |
| LastName | string | Indicates the last name of customer | N (PA) | PA: { "name": "LastName", "value": "Samudio Besada", "valueType": "string" } |
| OtherName | string | Indicates the other name of customer | N (PA) | PA: { "name": "OtherName", "value": "Del Carmen", "valueType": "string" } |
| CompanyName | string | Indicates the company name if the the acccount type is business. | N (PA) | PA: { "name": "CompanyName", "value": "**", "valueType": "string" } |
| Date-Of-Birth | string | date of birth of customer | N (PA) | PA: { "name": "Date-Of-Birth", "value": "1973-05-23T00:00:00-5:00", "valueType": "string" } |
| Customer Identity | array | this is an array with all the customer identity details. | N (PA) | PA: { "name": "Customer Identity", "valueType": "array", "value": [ { "DocumentType": "C", "DocumentNumber": "4-248-586", "DocumentDescription": "Cedula" } ] } |
Customer Identity Characteristic value Array- SubResource Model
| name | type | description | required (mandatory-Y, optional-N, Not applicable- N/A) | examples |
|---|---|---|---|---|
| DocumentType | string | The type of document | N (PA) | PA: { "DocumentType": "C", "DocumentNumber": "4-248-586", "DocumentDescription": "Cedula" } |
| DocumentNumber | string | Document ID/ Number. | N (PA) | PA: { "DocumentType": "C", "DocumentNumber": "4-248-586", "DocumentDescription": "Cedula" } |
| DocumentDescription | string | description of the document | N (PA) | PA: { "DocumentType": "C", "DocumentNumber": "4-248-586", "DocumentDescription": "Cedula" } |
Expected values for CSG FIXED Auto Pay
For paymentStatus below are expected fields Delinquency Status or Payment Status
Delinquency Status:
| Mule Field Value | BSS Field Value | Description |
|---|---|---|
| NORMAL | “” or null | NORMAL |
| C | C | VOLUNTARY DISC |
| E | E | NON-PAY DISC |
| A | A | OPEN NP EQPTACT |
| F | F | OPEN NP EQPT FT |
| P | P | PEND NP SVC RES |
| S | S | PND CHG SERV WO |
| T | T | PPV RESTRICTED |
| U | U | DWNGRD-SVCS |
| V | V | OPEN VOL DISC |
| W | W | OPEN NP EQPTDIS |
| Z | Z | CHARGED OFF |
Payment Status
| Mule Field Value | BSS Field Value | Description |
|---|---|---|
| NORMAL | “” or null | NORMAL |
| S | S | Suspended |
| B | B | Balance is less than EFT minimum debit amount |
| D | D | Debit Error |
| E | E | Prenote Error |
| G | G | EFT debit had been sent to ACH processor |
| P | P | Prenote Error |
| W | W | Waiting |
Key considerations
- Please refer the responses from following URL: DXP-UX API - BillingAccountByID
PA Implementation:
- Account details will be retrieved from Liberate by providing accountNumber as an input.
- Sending LOB as header is not required as this resource deals with the account.
- Possible Identity types for Liberate PA are C -Cedula, PP-Pasaporte, SS-Seguro Social, V-Cuenta Vieja.
- Possible values for PaymentStatus are "In Arrears", "Active".
Possible values for state:
- W-Activo
- D-Defecto
- C-Cesado
- E-Cierre
- F-Cerrada
- S-Especial
- B-Llamada Prohibida
For all the dateTime fields
- Any datetime before 1908-04-22 will show offset -05:18
- Any datetime on or after 1908-04-22 will show offset -05:00
PR Implementation:
FIXED (CSG):
- From this operation we can fetch Auto Pay is enabled or disabled, auto-pay date and day, Delinquency status, payment status and payment method EFT or Card.
- In the response, if PaymentPlan.planType is AutoPay Enable, AutoPay Date can be displayed in the extended Characteristics else AutoPay Date cannot be displayed.
PREPAID & POSTPAID:
- Account details and autopay status are retrieved from Salesforce using billingAccountNumber.
- Account details for a PREPAID account are retrieved from Salesforce using MSISDN.
- Account details and autopay status are retrieved from Salesforce using MSISDN.
- The client account balances are retrieved from Aria.
DC markets.
Account status will be derived using the offers linked to account. if any of the Suspended offers are present in account, then the account state would be considered as "Suspended". Below are the offers list.
| OFFER_ID | DISPLAY_VALUE |
|---|---|
| 51002454 | CUR Wireline Barring |
| 51006038 | CUR Wireless Barring |
| 51006040 | CUR Wireless CHCO Barring |
| 51006047 | SXM Wireless Barring |
| 51006143 | CUR Data Connectivity Barring |
| 51007682 | CUR Wireless CHCO Barring up to 10 Members |
| 51007683 | CUR Wireless CHCO Barring 11 to 50 Members |
| 51007688 | BES Wireless CHCO Barring up to 10 Members |
| 51009190 | CUR Wireless Disconnection Fees for Collections |
| 51009192 | BES Wireless Disconnection Fees for Collections |
| 51009694 | SXM Wireless Disconnection Fees for Collections |